WebCodecs VideoFrame Plane-Zugriff: Ein tiefer Einblick in die Manipulation von rohen Videodaten

Jahrelang schien hochleistungsfähige Videoverarbeitung im Webbrowser ein ferner Traum zu sein. Entwickler waren oft auf die Einschränkungen des <video>-Elements und der 2D-Canvas-API beschränkt, die, obwohl leistungsstark, Leistungsengpässe verursachten und den Zugriff auf die zugrunde liegenden rohen Videodaten begrenzten. Die Einführung der WebCodecs-API hat diese Landschaft grundlegend verändert und bietet einen Low-Level-Zugriff auf die integrierten Medien-Codecs des Browsers. Eines ihrer revolutionärsten Merkmale ist die Möglichkeit, über das VideoFrame-Objekt direkt auf die Rohdaten einzelner Videoframes zuzugreifen und diese zu manipulieren.

Dieser Artikel ist ein umfassender Leitfaden für Entwickler, die über die einfache Videowiedergabe hinausgehen möchten. Wir werden die Feinheiten des VideoFrame-Plane-Zugriffs untersuchen, Konzepte wie Farbräume und Speicherlayout entmystifizieren und praktische Beispiele liefern, um Sie in die Lage zu versetzen, die nächste Generation von In-Browser-Videoanwendungen zu erstellen, von Echtzeitfiltern bis hin zu anspruchsvollen Computer-Vision-Aufgaben.

Voraussetzungen

Um das Beste aus diesem Leitfaden herauszuholen, sollten Sie ein solides Verständnis für Folgendes haben:

• Modernes JavaScript: Einschließlich asynchroner Programmierung (async/await, Promises).
• Grundlegende Videokonzepte: Vertrautheit mit Begriffen wie Frames, Auflösung und Codecs ist hilfreich.
• Browser-APIs: Erfahrung mit APIs wie Canvas 2D oder WebGL ist vorteilhaft, aber nicht zwingend erforderlich.

Verständnis von Videoframes, Farbräumen und Planes

Bevor wir in die API eintauchen, müssen wir uns zunächst ein solides mentales Modell davon machen, wie die Daten eines Videoframes tatsächlich aussehen. Ein digitales Video ist eine Sequenz von Standbildern oder Frames. Jeder Frame ist ein Gitter aus Pixeln, und jedes Pixel hat eine Farbe. Wie diese Farbe gespeichert wird, wird durch den Farbraum und das Pixelformat definiert.

RGBA: Die Muttersprache des Webs

Die meisten Webentwickler sind mit dem RGBA-Farbmodell vertraut. Jedes Pixel wird durch vier Komponenten dargestellt: Rot, Grün, Blau und Alpha (Transparenz). Die Daten werden typischerweise interleaved (verschachtelt) im Speicher abgelegt, was bedeutet, dass die R-, G-, B- und A-Werte für ein einzelnes Pixel nacheinander gespeichert werden:

[R1, G1, B1, A1, R2, G2, B2, A2, ...]

In diesem Modell wird das gesamte Bild in einem einzigen, zusammenhängenden Speicherblock gespeichert. Wir können uns dies als eine einzige "Plane" (Ebene) von Daten vorstellen.

YUV: Die Sprache der Videokomprimierung

Videocodecs arbeiten jedoch selten direkt mit RGBA. Sie bevorzugen YUV- (oder genauer gesagt, Y'CbCr) Farbräume. Dieses Modell trennt Bildinformationen in:

• Y (Luma): Die Helligkeits- oder Graustufeninformation. Das menschliche Auge ist am empfindlichsten für Änderungen der Luma.
• U (Cb) und V (Cr): Die Chrominanz- oder Farbdifferenzinformation. Das menschliche Auge ist weniger empfindlich für Farbdetails als für Helligkeitsdetails.

Diese Trennung ist der Schlüssel zu einer effizienten Komprimierung. Durch die Reduzierung der Auflösung der U- und V-Komponenten – eine Technik, die als Chroma-Subsampling bezeichnet wird – können wir die Dateigröße bei minimalem wahrnehmbarem Qualitätsverlust erheblich reduzieren. Dies führt zu planaren Pixelformaten, bei denen die Y-, U- und V-Komponenten in separaten Speicherblöcken oder "Planes" gespeichert werden.

Ein gängiges Format ist I420 (ein Typ von YUV 4:2:0), bei dem für jeden 2x2-Pixelblock vier Y-Samples, aber nur ein U- und ein V-Sample vorhanden sind. Das bedeutet, dass die U- und V-Planes die halbe Breite und halbe Höhe der Y-Plane haben.

Das Verständnis dieses Unterschieds ist entscheidend, da WebCodecs Ihnen direkten Zugriff auf genau diese Planes gibt, so wie der Decoder sie bereitstellt.

Das VideoFrame-Objekt: Ihr Tor zu den Pixeldaten

Das zentrale Teil dieses Puzzles ist das VideoFrame-Objekt. Es repräsentiert einen einzelnen Frame eines Videos und enthält nicht nur die Pixeldaten, sondern auch wichtige Metadaten.

Wichtige Eigenschaften von VideoFrame

• format: Eine Zeichenkette, die das Pixelformat angibt (z. B. 'I420', 'NV12', 'RGBA').
• codedWidth / codedHeight: Die vollen Abmessungen des Frames, wie er im Speicher abgelegt ist, einschließlich jeglichen Paddings, das vom Codec benötigt wird.
• displayWidth / displayHeight: Die Abmessungen, die für die Anzeige des Frames verwendet werden sollen.
• timestamp: Der Präsentationszeitstempel des Frames in Mikrosekunden.
• duration: Die Dauer des Frames in Mikrosekunden.

Die magische Methode: copyTo()

Die primäre Methode zum Zugriff auf rohe Pixeldaten ist videoFrame.copyTo(destination, options). Diese asynchrone Methode kopiert die Plane-Daten des Frames in einen von Ihnen bereitgestellten Puffer.

• destination: Ein ArrayBuffer oder ein typisiertes Array (wie Uint8Array), das groß genug ist, um die Daten aufzunehmen.
• options: Ein Objekt, das angibt, welche Planes kopiert werden sollen und wie ihr Speicherlayout aussieht. Wenn es weggelassen wird, werden alle Planes in einen einzigen zusammenhängenden Puffer kopiert.

Die Methode gibt ein Promise zurück, das mit einem Array von PlaneLayout-Objekten aufgelöst wird, eines für jede Plane im Frame. Jedes PlaneLayout-Objekt enthält zwei entscheidende Informationen:

• offset: Der Byte-Offset, an dem die Daten dieser Plane innerhalb des Zielpuffers beginnen.
• stride: Die Anzahl der Bytes zwischen dem Anfang einer Pixelzeile und dem Anfang der nächsten Zeile für diese Plane.

Ein kritisches Konzept: Stride vs. Width

Dies ist eine der häufigsten Quellen für Verwirrung bei Entwicklern, die neu in der Low-Level-Grafikprogrammierung sind. Sie können nicht davon ausgehen, dass jede Zeile mit Pixeldaten dicht aufeinander folgt.

• Width (Breite) ist die Anzahl der Pixel in einer Zeile des Bildes.
• Stride (auch Pitch oder Zeilenschritt genannt) ist die Anzahl der Bytes im Speicher vom Anfang einer Zeile bis zum Anfang der nächsten.

Oft ist der stride größer als width * bytes_per_pixel. Das liegt daran, dass der Speicher oft aufgefüllt (gepadded) wird, um an Hardware-Grenzen (z. B. 32- oder 64-Byte-Grenzen) ausgerichtet zu sein, was eine schnellere Verarbeitung durch die CPU oder GPU ermöglicht. Sie müssen immer den Stride verwenden, um die Speicheradresse eines Pixels in einer bestimmten Zeile zu berechnen.

Das Ignorieren des Strides führt zu verzerrten oder fehlerhaften Bildern und inkorrektem Datenzugriff.

Praktisches Beispiel 1: Zugriff auf eine Graustufen-Plane und deren Anzeige

Beginnen wir mit einem einfachen, aber aussagekräftigen Beispiel. Die meisten Videos im Web sind in einem YUV-Format wie I420 kodiert. Die 'Y'-Plane ist praktisch eine vollständige Graustufendarstellung des Bildes. Wir können nur diese Ebene extrahieren und sie auf einem Canvas rendern.

async function displayGrayscale(videoFrame) {
  // Wir gehen davon aus, dass der videoFrame in einem YUV-Format wie 'I420' oder 'NV12' vorliegt.
  if (!videoFrame.format.startsWith('I4')) {
    console.error('Dieses Beispiel erfordert ein planares YUV 4:2:0-Format.');
    videoFrame.close();
    return;
  }

  const yPlaneInfo = videoFrame.layout[0]; // Die Y-Plane ist immer die erste.

  // Erstellen Sie einen Puffer, um nur die Daten der Y-Plane aufzunehmen.
  const yPlaneData = new Uint8Array(yPlaneInfo.stride * videoFrame.codedHeight);

  // Kopieren Sie die Y-Plane in unseren Puffer.
  await videoFrame.copyTo(yPlaneData, {
    rect: { x: 0, y: 0, width: videoFrame.codedWidth, height: videoFrame.codedHeight },
    layout: [yPlaneInfo]
  });

  // Jetzt enthält yPlaneData die rohen Graustufenpixel.
  // Wir müssen es rendern. Wir erstellen einen RGBA-Puffer für den Canvas.
  const canvas = document.getElementById('my-canvas');
  canvas.width = videoFrame.displayWidth;
  canvas.height = videoFrame.displayHeight;
  const ctx = canvas.getContext('2d');
  const imageData = ctx.createImageData(canvas.width, canvas.height);

  // Iterieren Sie über die Canvas-Pixel und füllen Sie sie mit den Daten der Y-Plane.
  for (let y = 0; y < videoFrame.displayHeight; y++) {
    for (let x = 0; x < videoFrame.displayWidth; x++) {
      // Wichtig: Verwenden Sie den Stride, um den korrekten Quellindex zu finden!
      const yIndex = y * yPlaneInfo.stride + x;
      const luma = yPlaneData[yIndex];

      // Berechnen Sie den Zielindex im RGBA ImageData-Puffer.
      const rgbaIndex = (y * canvas.width + x) * 4;

      imageData.data[rgbaIndex] = luma;     // Rot
      imageData.data[rgbaIndex + 1] = luma; // Grün
      imageData.data[rgbaIndex + 2] = luma; // Blau
      imageData.data[rgbaIndex + 3] = 255;  // Alpha
    }
  }

  ctx.putImageData(imageData, 0, 0);

  // KRITISCH: Schließen Sie immer den VideoFrame, um seinen Speicher freizugeben.
  videoFrame.close();
}

Dieses Beispiel hebt mehrere wichtige Schritte hervor: das Identifizieren des korrekten Plane-Layouts, das Zuweisen eines Zielpuffers, die Verwendung von copyTo zum Extrahieren der Daten und die korrekte Iteration über die Daten unter Verwendung des stride, um ein neues Bild zu erstellen.

Praktisches Beispiel 2: In-Place-Manipulation (Sepia-Filter)

Führen wir nun eine direkte Datenmanipulation durch. Ein Sepia-Filter ist ein klassischer Effekt, der einfach zu implementieren ist. Für dieses Beispiel ist es einfacher, mit einem RGBA-Frame zu arbeiten, den Sie möglicherweise von einem Canvas oder einem WebGL-Kontext erhalten.

async function applySepiaFilter(videoFrame) {
  // Dieses Beispiel geht davon aus, dass der Eingabe-Frame 'RGBA' oder 'BGRA' ist.
  if (videoFrame.format !== 'RGBA' && videoFrame.format !== 'BGRA') {
    console.error('Das Sepia-Filter-Beispiel erfordert einen RGBA-Frame.');
    videoFrame.close();
    return null;
  }

  // Weisen Sie einen Puffer zu, um die Pixeldaten aufzunehmen.
  const frameDataSize = videoFrame.allocationSize();
  const frameData = new Uint8Array(frameDataSize);
  await videoFrame.copyTo(frameData);

  const layout = videoFrame.layout[0]; // RGBA ist eine einzelne Plane

  // Manipulieren Sie nun die Daten im Puffer.
  for (let y = 0; y < videoFrame.codedHeight; y++) {
    for (let x = 0; x < videoFrame.codedWidth; x++) {
      const pixelIndex = y * layout.stride + x * 4; // 4 Bytes pro Pixel (R,G,B,A)

      const r = frameData[pixelIndex];
      const g = frameData[pixelIndex + 1];
      const b = frameData[pixelIndex + 2];

      const tr = 0.393 * r + 0.769 * g + 0.189 * b;
      const tg = 0.349 * r + 0.686 * g + 0.168 * b;
      const tb = 0.272 * r + 0.534 * g + 0.131 * b;

      frameData[pixelIndex] = Math.min(255, tr);
      frameData[pixelIndex + 1] = Math.min(255, tg);
      frameData[pixelIndex + 2] = Math.min(255, tb);
      // Alpha (frameData[pixelIndex + 3]) bleibt unverändert.
    }
  }

  // Erstellen Sie einen *neuen* VideoFrame mit den modifizierten Daten.
  const newFrame = new VideoFrame(frameData, {
    format: videoFrame.format,
    codedWidth: videoFrame.codedWidth,
    codedHeight: videoFrame.codedHeight,
    timestamp: videoFrame.timestamp,
    duration: videoFrame.duration
  });

  // Vergessen Sie nicht, den ursprünglichen Frame zu schließen!
  videoFrame.close();

  return newFrame;
}

Dies demonstriert einen vollständigen Lese-Änderungs-Schreib-Zyklus: Kopieren der Daten, Durchlaufen der Daten mit Hilfe des Strides, Anwenden einer mathematischen Transformation auf jedes Pixel und Erstellen eines neuen VideoFrame mit den resultierenden Daten. Dieser neue Frame kann dann auf einem Canvas gerendert, an einen VideoEncoder gesendet oder an einen anderen Verarbeitungsschritt übergeben werden.

Leistung ist entscheidend: JavaScript vs. WebAssembly (WASM)

Das Iterieren über Millionen von Pixeln für jeden Frame (ein 1080p-Frame hat über 2 Millionen Pixel oder 8 Millionen Datenpunkte in RGBA) kann in JavaScript langsam sein. Obwohl moderne JS-Engines unglaublich schnell sind, kann dieser Ansatz bei der Echtzeitverarbeitung von hochauflösendem Video (HD, 4K) den Hauptthread leicht überlasten, was zu einer ruckelnden Benutzererfahrung führt.

Hier wird WebAssembly (WASM) zu einem unverzichtbaren Werkzeug. Mit WASM können Sie Code, der in Sprachen wie C++, Rust oder Go geschrieben wurde, mit nahezu nativer Geschwindigkeit im Browser ausführen. Der Arbeitsablauf für die Videoverarbeitung sieht dann wie folgt aus:

1. In JavaScript: Verwenden Sie videoFrame.copyTo(), um die rohen Pixeldaten in einen ArrayBuffer zu bekommen.
2. An WASM übergeben: Übergeben Sie eine Referenz auf diesen Puffer an Ihr kompiliertes WASM-Modul. Dies ist eine sehr schnelle Operation, da keine Daten kopiert werden müssen.
3. In WASM (C++/Rust): Führen Sie Ihre hochoptimierten Bildverarbeitungsalgorithmen direkt auf dem Speicherpuffer aus. Dies ist um Größenordnungen schneller als eine JavaScript-Schleife.
4. Rückkehr zu JavaScript: Sobald WASM fertig ist, kehrt die Kontrolle zu JavaScript zurück. Sie können dann den modifizierten Puffer verwenden, um einen neuen VideoFrame zu erstellen.

Für jede ernsthafte Echtzeit-Videomanipulationsanwendung – wie virtuelle Hintergründe, Objekterkennung oder komplexe Filter – ist der Einsatz von WebAssembly nicht nur eine Option, sondern eine Notwendigkeit.

Umgang mit verschiedenen Pixelformaten (z. B. I420, NV12)

Obwohl RGBA einfach ist, erhalten Sie von einem VideoDecoder meistens Frames in planaren YUV-Formaten. Schauen wir uns an, wie man mit einem vollständig planaren Format wie I420 umgeht.

Ein VideoFrame im I420-Format hat drei Layout-Deskriptoren in seinem layout-Array:

• layout[0]: Die Y-Plane (Luma). Abmessungen sind codedWidth x codedHeight.
• layout[1]: Die U-Plane (Chroma). Abmessungen sind codedWidth/2 x codedHeight/2.
• layout[2]: Die V-Plane (Chroma). Abmessungen sind codedWidth/2 x codedHeight/2.

So würden Sie alle drei Planes in einen einzigen Puffer kopieren:

async function extractI420Planes(videoFrame) {
  const totalSize = videoFrame.allocationSize({ format: 'I420' });
  const allPlanesData = new Uint8Array(totalSize);

  const layouts = await videoFrame.copyTo(allPlanesData);

  // layouts ist ein Array von 3 PlaneLayout-Objekten
  console.log('Y Plane Layout:', layouts[0]); // { offset: 0, stride: ... }
  console.log('U Plane Layout:', layouts[1]); // { offset: ..., stride: ... }
  console.log('V Plane Layout:', layouts[2]); // { offset: ..., stride: ... }

  // Sie können jetzt auf jede Plane innerhalb des `allPlanesData`-Puffers zugreifen
  // unter Verwendung ihres spezifischen Offsets und Strides.

  const yPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[0].offset,
    layouts[0].stride * videoFrame.codedHeight
  );

  // Beachten Sie, dass die Chroma-Dimensionen halbiert sind!
  const uPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[1].offset,
    layouts[1].stride * (videoFrame.codedHeight / 2)
  );

  const vPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[2].offset,
    layouts[2].stride * (videoFrame.codedHeight / 2)
  );

  console.log('Accessed Y plane size:', yPlaneView.byteLength);
  console.log('Accessed U plane size:', uPlaneView.byteLength);

  videoFrame.close();
}

Ein weiteres gängiges Format ist NV12, das semi-planar ist. Es hat zwei Planes: eine für Y und eine zweite Plane, in der U- und V-Werte verschachtelt sind (z. B. [U1, V1, U2, V2, ...]). Die WebCodecs-API handhabt dies transparent; ein VideoFrame im NV12-Format hat einfach zwei Layouts in seinem layout-Array.

Herausforderungen und Best Practices

Auf dieser niedrigen Ebene zu arbeiten ist leistungsstark, bringt aber auch Verantwortungen mit sich.

Speicherverwaltung ist von größter Bedeutung

Ein VideoFrame beansprucht eine erhebliche Menge an Speicher, der oft außerhalb des Heaps des JavaScript-Garbage-Collectors verwaltet wird. Wenn Sie diesen Speicher nicht explizit freigeben, verursachen Sie ein Speicherleck, das den Browser-Tab zum Absturz bringen kann.

Rufen Sie immer, immer videoFrame.close() auf, wenn Sie mit einem Frame fertig sind.

Asynchrone Natur

Jeder Datenzugriff ist asynchron. Die Architektur Ihrer Anwendung muss den Fluss von Promises und async/await korrekt handhaben, um Race Conditions zu vermeiden und eine reibungslose Verarbeitungspipeline zu gewährleisten.

Browser-Kompatibilität

WebCodecs ist eine moderne API. Obwohl sie in allen gängigen Browsern unterstützt wird, überprüfen Sie immer ihre Verfügbarkeit und seien Sie sich über herstellerspezifische Implementierungsdetails oder Einschränkungen im Klaren. Verwenden Sie Feature-Erkennung, bevor Sie versuchen, die API zu nutzen.

Fazit: Eine neue Grenze für Web-Video

Die Fähigkeit, über die WebCodecs-API direkt auf die rohen Plane-Daten eines VideoFrame zuzugreifen und diese zu manipulieren, ist ein Paradigmenwechsel für webbasierte Medienanwendungen. Sie entfernt die Blackbox des <video>-Elements und gibt Entwicklern die granulare Kontrolle, die bisher nativen Anwendungen vorbehalten war.

Indem Sie die Grundlagen des Video-Speicherlayouts – Planes, Stride und Farbformate – verstehen und die Leistung von WebAssembly für leistungskritische Operationen nutzen, können Sie nun unglaublich anspruchsvolle Videoverarbeitungswerkzeuge direkt im Browser erstellen. Von Echtzeit-Farbkorrekturen und benutzerdefinierten visuellen Effekten bis hin zu clientseitigem maschinellem Lernen und Videoanalyse sind die Möglichkeiten riesig. Die Ära des hochleistungsfähigen Low-Level-Videos im Web hat wirklich begonnen.